拷貝檔案或目錄 (file.copy)
聲明
操作成敗, 錯誤資訊 = file.copy(來源路徑, 目標路徑 [, 模式])
參數
- 來源路徑
文字型,來源檔案或目錄的絕對路徑 - 目標路徑
文字型,拷貝後的檔案或目錄的完整絕對路徑,包含目標檔名或目錄名 - 模式 20250914+
文字型,可選參數,複製模式。取值:- 空字串或省略:預設模式(no-clobber),當目標已存在時回傳失敗
- "overwrite" 或 "o":覆蓋模式,直接替換已存在的目標(已存在的目標會被刪除)
- "merge" 或 "m":合併模式(僅用於目錄),保留目標中已存在的檔案
- "overwrite-merge" 或 "om"/"mo":覆蓋合併模式,合併目錄但覆蓋同名檔案
回傳值
- 操作成敗
布林型,操作成功回傳 true,操作失敗回傳 false - 錯誤資訊
文字型,操作失敗時的錯誤資訊
說明
將
來源路徑指向的檔案或目錄拷貝為目標路徑
該函式是「拷貝為」語義,不是「拷貝進」語義。目標路徑指定最終的檔案或目錄,不會自動追加來源檔名或目錄名;即使目標已存在且為目錄,或者目標路徑以/結尾,也不會將來源檔案或目錄放入該目錄中
例如,要把/a/b/c拷貝到/d/e/中並保留名稱c,目標路徑應寫為/d/e/c,不能只寫/d/e/
目標已存在時,按模式參數處理:預設模式回傳失敗,覆蓋模式替換目標本身,目錄合併模式則將來源目錄內容合併到目標目錄
關鍵詞:複製檔案、拷貝檔案、複製目錄、拷貝目錄、複製資料夾、拷貝資料夾
該函式在 20250313 以後的版本方可使用
範例
ok, err = file.copy(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('拷貝失敗:'..err)
end
注:上述程式碼中使用了非本章函式 sys.alert
拷貝到另一個目錄並保留名稱
-- 假設 /d/e 是已存在的目錄,/d/e/c 尚不存在
file.copy('/a/b/c', '/d/e/c') -- 正確:將 c 拷貝為 /d/e/c
-- 錯誤寫法:目標是 e 本身,不是 e 目錄中的 c
file.copy('/a/b/c', '/d/e/') -- 預設模式下因目標已存在而失敗
-- 覆蓋模式會替換 e 本身,不會生成 /d/e/c(20250914+)
-- file.copy('/a/b/c', '/d/e/', 'overwrite')
封裝「拷貝進目錄」函式
以下為自訂封裝範例,需要 20250914 以後的版本。目標目錄須已存在,函式會保留來源檔案或目錄名,並將可選的 mode 參數傳給 file.copy。發生同名衝突時,仍按指定模式處理。
local function file_copy_into(src_path, dst_dir, mode)
if file.exists(dst_dir) ~= "directory" then
return false, "Target is not a directory"
end
local name, err = file.path.last_component(src_path)
if not name then
return false, err
end
-- 避免將目標目錄本身或其父目錄作為最終目標。
if name == "" or name == "/" or name == "." or name == ".." then
return false, "Source path must end with a file or directory name"
end
local dst_path, path_err = file.path.add_component(dst_dir, name)
if not dst_path then
return false, path_err
end
return file.copy(src_path, dst_path, mode)
end
-- 假設 /d/e 是已存在的目錄,將 c 拷貝為 /d/e/c
local ok, err = file_copy_into("/a/b/c", "/d/e/")
if not ok then
print("拷貝失敗:"..err)
end
-- 如需替換 /d/e/c,可在呼叫時指定覆蓋模式:
-- file_copy_into("/a/b/c", "/d/e/", "overwrite")
注:上述程式碼使用了 file.exists、file.path.last_component 和 file.path.add_component。